home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / listbox.n < prev    next >
Text File  |  1994-09-20  |  12KB  |  331 lines
  1.  
  2.  
  3.  
  4. listbox(n)                 Tk Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      listbox - Create and manipulate listbox widgets
  12.  
  13. SYNOPSIS
  14.      listbox _p_a_t_h_N_a_m_e ?_o_p_t_i_o_n_s?
  15.  
  16. STANDARD OPTIONS
  17.      background      foreground     selectBackgroundxScrollCommand |
  18.      borderWidth     font           selectBorderWidthyScrollCommand|
  19.      cursor          geometry       selectForeground               |
  20.      exportSelection relief         setGrid                        |
  21.  
  22.      See the ``options'' manual entry for details on the standard
  23.      options.
  24.  
  25. WIDGET-SPECIFIC OPTIONS
  26.      None.
  27. _________________________________________________________________
  28.  
  29.  
  30. DESCRIPTION
  31.      The listbox command creates a new window (given by the _p_a_t_h_-
  32.      _N_a_m_e  argument)  and  makes it into a listbox widget.  Addi-
  33.      tional options, described above, may  be  specified  on  the
  34.      command  line or in the option database to configure aspects
  35.      of the listbox such as its colors, font, text,  and  relief.
  36.      The  listbox  command returns its _p_a_t_h_N_a_m_e argument.  At the
  37.      time this command is invoked, there must not exist a  window
  38.      named _p_a_t_h_N_a_m_e, but _p_a_t_h_N_a_m_e's parent must exist.
  39.  
  40.      A listbox is a widget that displays a list of  strings,  one
  41.      per line.  When first created, a new listbox has no elements
  42.      in its list.  Elements may be added or deleted using  widget
  43.      commands described below.  In addition, one or more elements
  44.      may be selected as described below.  If a listbox is export-  |
  45.      ing its selection (see exportSelection option), then it will  |
  46.      observe the standard X11 protocols for handling  the  selec-
  47.      tion;  listbox selections are available as type STRING, con-
  48.      sisting of a Tcl list with one entry for each selected  ele-
  49.      ment.
  50.  
  51.      For large lists only a subset of the list elements  will  be
  52.      displayed in the listbox window at once;  commands described
  53.      below may be used to change the view in the  window.   List-
  54.      boxes  allow scrolling in both directions using the standard  |
  55.      xScrollCommand and yScrollCommand options.  They  also  sup-
  56.      port scanning, as described below.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. listbox(n)                 Tk Commands
  71.  
  72.  
  73.  
  74. WIDGET COMMAND
  75.      The listbox command creates a new Tcl command whose name  is
  76.      _p_a_t_h_N_a_m_e.  This command may be used to invoke various opera-
  77.      tions on the widget.  It has the following general form:
  78.  
  79.           _p_a_t_h_N_a_m_e _o_p_t_i_o_n ?_a_r_g _a_r_g ...?
  80.  
  81.      _O_p_t_i_o_n and the _a_r_gs determine the exact behavior of the com-
  82.      mand.  The following commands are possible for listbox widg-
  83.      ets:
  84.  
  85.      _p_a_t_h_N_a_m_e configure ?_o_p_t_i_o_n? ?_v_a_l_u_e _o_p_t_i_o_n _v_a_l_u_e ...?
  86.           Query  or  modify  the  configuration  options  of  the
  87.           widget.   If  no  _o_p_t_i_o_n  is  specified, returns a list
  88.           describing all of the available  options  for  _p_a_t_h_N_a_m_e
  89.           (see  Tk_ConfigureInfo for information on the format of
  90.           this list).  If _o_p_t_i_o_n is specified with no _v_a_l_u_e, then
  91.           the  command  returns  a  list describing the one named
  92.           option (this list will be identical to the  correspond-
  93.           ing  sublist  of  the  value  returned  if no _o_p_t_i_o_n is
  94.           specified).  If one  or  more  _o_p_t_i_o_n-_v_a_l_u_e  pairs  are
  95.           specified,  then  the command modifies the given widget
  96.           option(s) to have the given value(s);  in this case the
  97.           command  returns  an empty string.  _O_p_t_i_o_n may have any
  98.           of the values accepted by the listbox command.
  99.  
  100.      _p_a_t_h_N_a_m_e curselection
  101.           Returns a list containing the indices  of  all  of  the  |
  102.           elements  in  the  listbox that are currently selected.  |
  103.           If there are no elements selected in the  listbox  then  |
  104.           an empty string is returned.
  105.  
  106.      _p_a_t_h_N_a_m_e delete _f_i_r_s_t ?_l_a_s_t?
  107.           Delete one or more elements of the listbox.  _F_i_r_s_t  and
  108.           _l_a_s_t  give  the  integer  indices of the first and last
  109.           elements in the range to be  deleted.   If  _l_a_s_t  isn't
  110.           specified  it  defaults to _f_i_r_s_t, i.e. a single element
  111.           is deleted.  An index of 0  corresponds  to  the  first
  112.           element  in  the  listbox.  Either _f_i_r_s_t or _l_a_s_t may be
  113.           specified as end, in which case it refers to  the  last
  114.           element  of the listbox.  This command returns an empty
  115.           string
  116.  
  117.      _p_a_t_h_N_a_m_e get _i_n_d_e_x
  118.           Return the contents of the listbox element indicated by
  119.           _i_n_d_e_x.    _I_n_d_e_x  must  be  a  non-negative  integer  (0
  120.           corresponds to the first element in the listbox), or it
  121.           may  also be specified as end to indicate the last ele-
  122.           ment in the listbox.
  123.  
  124.      _p_a_t_h_N_a_m_e insert _i_n_d_e_x ?_e_l_e_m_e_n_t _e_l_e_m_e_n_t ...?
  125.           Insert zero or more  new  elements  in  the  list  just
  126.           before  the  element  given  by  _i_n_d_e_x.   If  _i_n_d_e_x  is
  127.  
  128.  
  129.  
  130. Tk                                                              2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. listbox(n)                 Tk Commands
  137.  
  138.  
  139.  
  140.           specified as end then the new elements are added to the
  141.           end of the list.  Returns an empty string.
  142.  
  143.      _p_a_t_h_N_a_m_e nearest _y
  144.           Given a y-coordinate within the  listbox  window,  this
  145.           command returns the index of the (visible) listbox ele-
  146.           ment nearest to that y-coordinate.
  147.  
  148.      _p_a_t_h_N_a_m_e scan _o_p_t_i_o_n _a_r_g_s
  149.           This command is used to  implement  scanning  on  list-
  150.           boxes.  It has two forms, depending on _o_p_t_i_o_n:
  151.  
  152.           _p_a_t_h_N_a_m_e scan mark _x _y
  153.                Records _x and _y and the current view in the  list-  |
  154.                box  window;   used in conjunction with later scan  |
  155.                dragto commands.  Typically this command is  asso-  |
  156.                ciated  with  a  mouse button press in the widget.  |
  157.                It returns an empty string.                         |
  158.  
  159.           _p_a_t_h_N_a_m_e scan dragto _x _y.                                     ||
  160.                This command computes the difference between its _x  |
  161.                and _y arguments and the _x and _y arguments  to  the  |
  162.                last  scan  mark  command for the widget.  It then  |
  163.                adjusts the view by 10  times  the  difference  in  |
  164.                coordinates.  This command is typically associated
  165.                with mouse motion events in the widget, to produce
  166.                the  effect  of  dragging  the  list at high speed
  167.                through the window.  The return value is an  empty
  168.                string.
  169.  
  170.      _p_a_t_h_N_a_m_e select _o_p_t_i_o_n _a_r_g
  171.           This command is used to adjust the selection  within  a
  172.           listbox.   It  has  several forms, depending on _o_p_t_i_o_n.
  173.           In all of the forms the index end refers  to  the  last
  174.           element in the listbox.
  175.  
  176.           _p_a_t_h_N_a_m_e select adjust _i_n_d_e_x
  177.                Locate the end of the  selection  nearest  to  the
  178.                element given by _i_n_d_e_x, and adjust that end of the
  179.                selection to be at _i_n_d_e_x (i.e  including  but  not
  180.                going  beyond _i_n_d_e_x).  The other end of the selec-
  181.                tion is made the anchor point for future select to
  182.                commands.  If the selection isn't currently in the
  183.                listbox, then this command  is  identical  to  the
  184.                select  from  widget  command.   Returns  an empty
  185.                string.
  186.  
  187.           _p_a_t_h_N_a_m_e select clear
  188.                If the selection is in this  listbox  then  it  is  |
  189.                cleared so that none of the listbox's elements are  |
  190.                selected anymore.
  191.  
  192.  
  193.  
  194.  
  195. Tk                                                              3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. listbox(n)                 Tk Commands
  203.  
  204.  
  205.  
  206.           _p_a_t_h_N_a_m_e select from _i_n_d_e_x
  207.                Set the selection to consist of element _i_n_d_e_x, and
  208.                make  _i_n_d_e_x  the anchor point for future select to
  209.                widget commands.  Returns an empty string.
  210.  
  211.           _p_a_t_h_N_a_m_e select to _i_n_d_e_x
  212.                Set the selection to consist of the elements  from
  213.                the anchor point to element _i_n_d_e_x, inclusive.  The
  214.                anchor point is  determined  by  the  most  recent
  215.                select  from  or  select  adjust  command  in this
  216.                widget.  If the selection isn't  in  this  widget,
  217.                this command is identical to select from.  Returns
  218.                an empty string.
  219.  
  220.      _p_a_t_h_N_a_m_e size
  221.           Returns a decimal string indicating the total number of
  222.           elements in the listbox.
  223.  
  224.      _p_a_t_h_N_a_m_e xview _i_n_d_e_x
  225.           Adjust the view in the listbox so that character  posi-  |
  226.           tion _i_n_d_e_x is displayed at the left edge of the widget.  |
  227.           Returns an empty string.                                 |
  228.  
  229.      _p_a_t_h_N_a_m_e yview _i_n_d_e_x                                               ||
  230.           Adjust the view in the listbox so that element _i_n_d_e_x is  |
  231.           displayed at the top of the widget.  If _i_n_d_e_x is speci-  |
  232.           fied  as end it indicates the last element of the list-  |
  233.           box.  Returns an empty string.
  234.  
  235.  
  236. DEFAULT BINDINGS
  237.      Tk automatically creates class bindings for  listboxes  that  |
  238.      give them the following default behavior:                     |
  239.  
  240.      [1]                                                                ||
  241.           When  button  1  is pressed over a listbox, the element  |
  242.           underneath the mouse cursor is selected.  The mouse can  |
  243.           be dragged to select a range of elements.                |
  244.  
  245.      [2]                                                                ||
  246.           The  ends  of the selection can be adjusted by dragging  |
  247.           with mouse button 1 while the shift key is down;   this  |
  248.           will  adjust  the end of the selection that was nearest  |
  249.           to the mouse cursor when button 1 was pressed.           |
  250.  
  251.      [3]                                                                ||
  252.           The  view  in  the  listbox can be adjusted by dragging  |
  253.           with mouse button 2.                                     |
  254.  
  255.      The behavior of listboxes can be  changed  by  defining  new  |
  256.      bindings  for  individual widgets or by redefining the class  |
  257.      bindings.  In addition, the procedure tk_listboxSingleSelect  |
  258.  
  259.  
  260.  
  261. Tk                                                              4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. listbox(n)                 Tk Commands
  269.  
  270.  
  271.  
  272.      may  be  invoked  to  change listbox behavior so that only a  |
  273.      single element may be selected at once.
  274.  
  275.  
  276. KEYWORDS
  277.      listbox, widget
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327. Tk                                                              5
  328.  
  329.  
  330.  
  331.